Velodyne Points / KITTI Raw 3D#

Format specification#

Velodyne Points / KITTI Raw 3D data format homepage is available here.

Velodyne Points / KITTI Raw 3D data format specification is available here.

Supported annotation types:

Cuboid3d (represent tracks)

Supported annotation attributes:

truncation (write, string), possible values: truncation_unset, in_image, truncated, out_image, behind_image (case-independent).
occlusion (write, string), possible values: occlusion_unset, visible, partly, fully (case-independent). This attribute has priority over occluded.
occluded (read/write, boolean)
keyframe (read/write, boolean). Responsible for occlusion_kf field.
track_id (read/write, integer). Indicates the group over frames for annotations, represent tracks.

Supported image attributes:

frame (read/write, integer). Indicates frame number of the image.

Convert KITTI Raw dataset#

The velodyne points/KITTI Raw dataset is available for download here and here.

A KITTI Raw dataset can be converted in the following way:

datum convert --input-format kitti_raw --input-path <path/to/dataset> \
    --output-format <desired_format> --output-dir <output/dir>

KITTI Raw dataset directory should have the following structure:

└─ Dataset/
    ├── dataset_meta.json # a list of custom labels (optional)
    ├── image_00/ # optional, aligned images from different cameras
    │   └── data/
    │       ├── <name1.ext>
    │       └── <name2.ext>
    ├── image_01/
    │   └── data/
    │       ├── <name1.ext>
    │       └── <name2.ext>
    ...
    │
    ├── velodyne_points/ # optional, 3d point clouds
    │   └── data/
    │       ├── <name1.pcd>
    │       └── <name2.pcd>
    ├── tracklet_labels.xml
    └── frame_list.txt # optional, required for custom image names

The format does not support arbitrary image names and paths, but Datumaro provides an option to use a special index file to allow this.

frame_list.txt contents:

12345 relative/path/to/name1/from/data
46 relative/path/to/name2/from/data
...

To add custom classes, you can use dataset_meta.json.

Export to other formats#

Datumaro can convert a KITTI Raw dataset into any other format Datumaro supports.

Such conversion will only be successful if the output format can represent the type of dataset you want to convert, e.g. 3D point clouds can be saved in Supervisely Point Clouds format, but not in COCO keypoints.

There are several ways to convert a KITTI Raw dataset to other dataset formats:

datum convert --input-format kitti_raw --input-path <path/to/kitti_raw> \
    --output-format sly_pointcloud --output-dir <output/dir>

Or, using Python API:

import datumaro as dm

dataset = dm.Dataset.import_from('<path/to/dataset>', 'kitti_raw')
dataset.export('save_dir', 'sly_pointcloud', save_media=True)

Export to KITTI Raw#

There are several ways to convert a dataset to KITTI Raw format:

# converting to KITTI Raw format from other format
datum convert --input-format sly_pointcloud --input-path <path/to/dataset> \
    --output-format kitti_raw --output-dir <output/dir> -- --save-media --reindex

Extra options for exporting to KITTI Raw format:

--save-media allow to export dataset with saving media files. This will include point clouds and related images (by default False)
--image-ext IMAGE_EXT allow to specify image extension for exporting dataset (by default - keep original or use .png, if none)
--reindex assigns new indices to frames and tracks. Allows annotations without track_id attribute (they will be exported as single-frame tracks).
--allow-attrs allows writing arbitrary annotation attributes. They will be written in <annotations> section of <poses><item> (disabled by default)

Examples#

Example 1. Convert dataset and compute statistics#

datum convert --input-format kitti_raw --input-path ../kitti_raw/ \
    --output-format datumaro --output-dir ./output_project
datum stats --input-path ./output_project

Example 2. Convert Supervisely Pointclouds to KITTI Raw#

datum convert --input-format sly_pointcloud --input-path ../sly_pcd/ \
    --output-format kitti_raw --output-dir my_kitti/ -- --save-media --allow-attrs

Example 3. Create a custom dataset#

import numpy as np
import datumaro as dm

dataset = dm.Dataset.from_iterable([
    dm.DatasetItem(id='some/name/qq',
        annotations=[
            dm.Cuboid3d(position=[13.54, -9.41, 0.24], label=0,
                attributes={'occluded': False, 'track_id': 1}),

            dm.Cuboid3d(position=[3.4, -2.11, 4.4], label=1,
                attributes={'occluded': True, 'track_id': 2})
        ],
        pcd='path/to/pcd1.pcd',
        related_images=[np.ones((10, 10)), 'path/to/image2.png', 'image3.jpg'],
        attributes={'frame': 0}
    ),
], categories=['cat', 'dog'])

dataset.export('my_dataset/', format='kitti_raw', save_media=True)

Examples of using this format from the code can be found in the format tests