Metadata-Version: 2.1
Name: kapture
Version: 1.0.17
Summary: kapture: file format for SfM
Home-page: https://github.com/naver/kapture/
Author: naverlabs
Author-email: kapture@naverlabs.com
License: UNKNOWN
Description: ![KAPTURE](assets/kapture_logo.svg)
        
        ![Continuous Integration
        Status](https://github.com/naver/kapture/workflows/kapture-main/badge.svg)
        
        # 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
        
        Finally, many popular datasets can directly be downloaded using the
        convenient
        [downloader](https://github.com/naver/kapture/blob/main/doc/tutorial.adoc#download-a-dataset)!
        
        # 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
        
            pip install kapture
        
        or see [installation](doc/installation.adoc) for more detailed
        instructions.
        
        ## Using docker
        
        Build the docker image:
        
            # build the docker image : if you have already cloned the repository
            docker build . -t kapture/kapture
            # OR build the docker image directly from github
            docker build git://github.com/naver/kapture -t kapture/kapture
            # run unit tests
            docker run -it --rm kapture/kapture python3 -m unittest discover -s /opt/src/kapture/tests
        
        If you want to process your own data, you can bind directories between
        the host and the container using `--volume` or `--mount` option (See the
        [docker documentation](https://docs.docker.com/storage/bind-mounts/)).
        The following example mounts `/path/to/dataset/` from the host to
        `/dataset` inside the docker.
        
            docker run -it \
                --rm \ # Automatically remove the container when it exits \
                --volume /path/to/dataset/:/dataset:ro \ #read only
                kapture/kapture
        
        ## kapture Python library
        
        See the
        [tutorial](https://github.com/naver/kapture/blob/main/doc/tutorial.adoc#using-kapture-in-your-code)
        for some examples using the kapture Python library.
        
        ## kapture tools
        
        In this repository, you will find a set of **conversion tools** to or
        from kapture format. Import results to kapture format, and conversely,
        export converts kapture data to other formats. Depending of the format,
        some data might not be converted, either because the other format does
        not support it (`—`) or because its was not implemented (`⨉`). Here is a
        table summarizing the conversion capabilities:
        
        <table style="width:100%;">
        <caption>conversion capabilities</caption>
        <colgroup>
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        <col style="width: 7%" />
        </colgroup>
        <thead>
        <tr class="header">
        <th style="text-align: left;">Format</th>
        <th style="text-align: left;">← →</th>
        <th style="text-align: left;">cam</th>
        <th style="text-align: left;">rig</th>
        <th style="text-align: left;">img</th>
        <th style="text-align: left;">trj</th>
        <th style="text-align: left;">gps</th>
        <th style="text-align: left;">kpt</th>
        <th style="text-align: left;">dsc</th>
        <th style="text-align: left;">gft</th>
        <th style="text-align: left;">p3D</th>
        <th style="text-align: left;">obs</th>
        <th style="text-align: left;">mch</th>
        </tr>
        </thead>
        <tbody>
        <tr class="odd">
        <td style="text-align: left;"><p>colmap</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>(✓)</p></td>
        </tr>
        <tr class="even">
        <td style="text-align: left;"><p>export</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>(✓)</p></td>
        <td></td>
        </tr>
        <tr class="odd">
        <td style="text-align: left;"><p>openmvg</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="even">
        <td style="text-align: left;"><p>export</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td></td>
        </tr>
        <tr class="odd">
        <td style="text-align: left;"><p>OpenSfM</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        </tr>
        <tr class="even">
        <td style="text-align: left;"><p>export</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td></td>
        </tr>
        <tr class="odd">
        <td style="text-align: left;"><p>bundler</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="even">
        <td style="text-align: left;"><p>image_folder</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="odd">
        <td style="text-align: left;"><p>image_list</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="even">
        <td style="text-align: left;"><p>nvm</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="odd">
        <td style="text-align: left;"><p>IDL_dataset_cvpr17</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="even">
        <td style="text-align: left;"><p>RobotCar_Seasons</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>?</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>?</p></td>
        </tr>
        <tr class="odd">
        <td style="text-align: left;"><p>ROSbag cameras+trajectory</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>(✓)</p></td>
        <td style="text-align: left;"><p>(✓)</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>⨉</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="even">
        <td style="text-align: left;"><p>SILDa</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        <tr class="odd">
        <td style="text-align: left;"><p>virtual_gallery</p></td>
        <td style="text-align: left;"><p>import</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>✓</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        <td style="text-align: left;"><p>—</p></td>
        </tr>
        </tbody>
        </table>
        
        conversion capabilities
        
        -   `✓`: supported, `(✓)` partially supported, `⨉`: not implemented,
            `—`: not supported by format.
        
        -   `cam`: handle camera parameters, eg. intrisics
        
        -   `rig`: handle rig structure.
        
        -   `img`: handle the path to images.
        
        -   `trj`: handle trajectories, eg. poses.
        
        -   `kpt`: handle image keypoints locations.
        
        -   `dsc`: handle image keypoints descriptors.
        
        -   `gft`: handle global image feature descriptors.
        
        -   `p3D`: handle 3D point clouds.
        
        -   `obs`: handle observations, ie. 3D-points / 2D keypoints
            correspondences.
        
        -   `mch`: handle keypoints matches.
        
        # kapture support in other packages
        
        ## Local Features
        
        -   [R2D2](https://arxiv.org/abs/1906.06195) local features can be
            directly generated in kapture format. See
            [here](https://github.com/naver/r2d2#feature-extraction-with-kapture-datasets)
        
        -   [D2-Net](https://arxiv.org/abs/1905.03561) features can also be
            extracted in kapture format. See instructions
            [here](https://github.com/mihaidusmanu/d2-net#feature-extraction-with-kapture-datasets).
        
        ## Global Features
        
        -   [AP-GeM](https://europe.naverlabs.com/research/computer-vision-research-naver-labs-europe/learning-visual-representations/deep-image-retrieval/)
            global feature extractor in kapture format:
            [here](https://github.com/naver/deep-image-retrieval#feature-extraction-with-kapture-datasets)
        
        # Datasets
        
        The kapture package provides conversion tools for several data formats
        and datasets used in the domain. But it also provides a tool to download
        datasets already converted to kapture. See the [kapture
        tutorial](doc/tutorial.adoc) for instructions to use the dataset
        downloader.
        
        Here is a list of datasets you can directly download in kapture format
        with the downloader tool:
        
        -   Datasets from the [Long Term Visual Localization
            site](https://www.visuallocalization.net/datasets/):
        
            -   Aachen Day Night v1.1
        
            -   Extended CMU-Seasons
        
            -   RobotCar Seasons v2
        
            -   InLoc (without images)
        
            -   SILDa Weather and Time of Day
        
        -   [Virtual
            Gallery](https://europe.naverlabs.com/research/3d-vision/virtual-gallery-dataset/)
            dataset
        
        # kapture-localization
        
        Checkout
        [kapture-localization](https://github.com/naver/kapture-localization),
        our toolbox which contains implementations for various localization
        related algorithms.
        
        -   mapping and localization pipelines with custom features
        
        -   mapping and localization pipelines with SIFT and vocabulary tree
            matching (default colmap pipeline)
        
        -   image retrieval benchmark (global sfm, local sfm, pose
            approximation)
        
        # Tutorial
        
        See the [kapture tutorial](doc/tutorial.adoc) for a short introduction
        to:
        
        -   conversion tools
        
        -   using kapture in your code
        
        -   dataset download
        
        # Contributing
        
        There are many ways to contribute to the kapture project:
        
        -   provide feedback and suggestions of improvements
        
        -   submit bug reports in the project bug tracker
        
        -   provide a dataset in kapture format that we can add to the
            downloader tool
        
        -   implement a feature or bug-fix for an outstanding issue
        
        -   add support of kapture format in other software packages (e.g. SfM
            pipelines…​), thus adding support for more datasets
        
        -   provide scripts to create data in kapture format (e.g. local/global
            feature extraction)
        
        -   propose a new feature and implement it
        
        If you wish to contribute, please refer to the
        [CONTRIBUTING](CONTRIBUTING.adoc) page.
        
        # License
        
        Software license is detailed in the [LICENSE](LICENSE) file.
        
        # Contact Us
        
        You can contact us through [GitHub](https://github.com/naver/kapture),
        or at kapture at naverlabs + com
        
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
Provides-Extra: dev
