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
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. 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.
        
        
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
