Vehicle Lidar Calibration API

Introduction

The API requires the client to upload the PCD, and configuration for vehicle lidar setup in a zip file (.zip extension) in the format defined below. The contents of the zip file are called a dataset.

1. The client makes an Upload and calibrate API call, which uploads their files and runs the calibration algorithm on the lidar files for the given configuration.

2. The calibration process is completed without errors if the Upload and calibrate API call response contains dataset_id, extrinsic_parameters, and error_stats.

3. The client can call the Get Extrinsic Parameters API using the dataset_id obtained from the Upload and calibrate API. This API responds with dataset_id, extrinsic_parameters, and error_stats.

Folder Structure

We require lidar frames for a given calibration.

1. Place the Lidar data captured from the LiDAR in a folder.

2. config.json contains configuration details of the calibration (intrinsic parameters, calibration name, etc.)

Note: Folder structure is optional. Users can place all files in the main directory and zip it.

Note

1. The folder and lidar file names shown here are for demonstration purposes. Users should avoid using spaces in the folder and the lidar filename.

2. The name of the JSON file should be config.json (case sensitive)

config.json for multitarget

{
    "calibration_name": "Lidar vehicle testing ",
    "calibration_type": "lidar_vehicle_calibration",
    "calibration_group_id": "xxxxxxxxxxxxxxxxxx",
    "is_lidar_tilted": false,
    "lidar_ground_height": 1.24,
    "vehicle_configuration":
    {
        "vehicle_shape": "rectangle",
        "wheelbase": 1.2,
        "track": 1.2,
        "front_wheel_overhang": 0,
        "rear_wheel_overhang": 0
    },
    "is_targetless_3d_lidar": false,
    "is_2d_lidar": false,
    "auto_detect_lidar_board": true,
    "multi_target": true,
    "targets":
    {
        "left":
        {
            "length": 1.2,
            "width": 1.8
        },
        "right":
        {
            "length": 1.2,
            "width": 1.8
        },
        "front":
        {
            "length": 1.2,
            "width": 1.8
        }
    },
    "use_bounding_box_on_board_detection_failure": false,
    "bounding_box":
    {
        "left":
        {
            "xmin": 1,
            "xmax": 1,
            "ymin": 1,
            "ymax": 1,
            "zmin": 1,
            "zmax": 1
        },
        "right":
        {
            "xmin": 1,
            "xmax": 1,
            "ymin": 1,
            "ymax": 1,
            "zmin": 1,
            "zmax": 1
        },
        "front":
        {
            "xmin": 1,
            "xmax": 1,
            "ymin": 1,
            "ymax": 1,
            "zmin": 1,
            "zmax": 1
        }
    },
    "all_lidar_data":
    [
        {
            "lidar_name": "Main Lidar",
            "laser_channels": 16,
            "lidar_type": "directional",
            "lidar_fov_direction": "front",
            "board_configuration_data":
            {
                "front_board_distance": 1.8,
                "left_board_distance": 0.6,
                "right_board_distance": 0.6
            }
        }
    ],
    "data":
    {
        "files":
        {
            "file": "lidar/lidardata.pcd"
        }
    }
}

Sample config.json

config.json for a Single target

{
    "calibration_name": "Lidar vehicle testing ",
    "calibration_type": "lidar_vehicle_calibration",
    "calibration_group_id": "xxxxxxxxxxxxxxxxxx",
    "vehicle_configuration":
    {
        "vehicle_shape": "rectangle",
        "wheelbase": 1.2,
        "track": 1.2,
        "front_wheel_overhang": 0.9,
        "rear_wheel_overhang": 0.86
    },
    "is_targetless_3d_lidar": false,
    "is_2d_lidar": false,
    "auto_detect_lidar_board": true,
    "multi_target": false,
    "is_lidar_tilted": false,
    "lidar_ground_height": 1.24,
    "targets":
    {
        "left":
        {
            "length": 1,
            "width": 0.6
        },
        "right":
        {
            "length": 1,
            "width": 0.6
        },
        "front":
        {
            "length": 1,
            "width": 0.6
        }
    },
    "use_bounding_box_on_board_detection_failure": false,
    "bounding_box":
    {
        "left":
        {
            "xmin": 1,
            "xmax": 1,
            "ymin": 1,
            "ymax": 1,
            "zmin": 1,
            "zmax": 1
        },
        "right":
        {
            "xmin": 1,
            "xmax": 1,
            "ymin": 1,
            "ymax": 1,
            "zmin": 1,
            "zmax": 1
        },
        "front":
        {
            "xmin": 1,
            "xmax": 1,
            "ymin": 1,
            "ymax": 1,
            "zmin": 1,
            "zmax": 1
        }
    },
    "all_lidar_data":
    [
        {
            "lidar_name": "Main Lidar",
            "lidar_config": 16,
            "lidar_type": "directional",
            "lidar_fov_direction": "front",
            "board_configuration_data":
            {
                "front_board_distance": 0.5,
                "left_board_distance": 0.5,
                "right_board_distance": 0.5
            }
        }
    ],
    "data":
    {
        "files":
        {
            "left": "lidar/left_0.5.pcd",
            "right": "lidar/right_0.5.pcd",
            "front": "lidar/front_0.5.pcd"
        }
    }
}

Sample config.json

config.json for targetless calibration

{
    "calibration_name": "Lidar vehicle testing ",
    "calibration_type": "lidar_vehicle_calibration",
    "calibration_group_id": "xxxxxxxxxxxxxxxxxx",
    "is_targetless_3d_lidar": true,
    "is_2d_lidar": false,
    "slam_algorithm_to_use": "ICP",
    "all_lidar_data":
    [
        {
            "lidar_name": "Main Lidar",
            "laser_channels": 64,
            "ground_rectangle_length": 20,
            "ground_rectangle_breadth": 20
        }
    ],
    "data":
    {
        "files":
        [
            "1.pcd",
            "2.pcd",
            "3.pcd",
            "4.pcd",
            "5.pcd",
            "6.pcd",
            "7.pcd",
            "8.pcd",
            "9.pcd",
            "10.pcd",
            "11.pcd",
            "12.pcd",
            "13.pcd",
            "14.pcd",
            "15.pcd",
            "16.pcd",
            "17.pcd",
            "18.pcd",
            "19.pcd",
            "20.pcd",
            "21.pcd",
            "22.pcd"
        ]
    }
}

Sample config.json

config.json key description

Quickstart

Before invoking the APIs, the client must obtain the clientId and auth token from Deepen AI. If you are a calibration admin, you can create different Access Tokens using the UI and use those instead. clientId is part of the path parameters in most API calls, and the auth token should be prefixed with “Bearer “ and passed to the ‘Authorization’ header in all API requests. How to get Access Tokens can be found on the following link: Access token for APIs

Upload file and calibrate

This POST API call sends a zip file to the server and runs the calibration algorithm. As the response, it returns dataset_id, extrinsic_parameters, and error_stats (error_stats won't be available for targetless calibration) to the user.

https://tools.calibrate.deepen.ai/api/v2/external/clients/{clientId}/calibration_dataset

Request

Path parameters

Body

Response

{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "calibration_algorithm_version": "target_based:v1.01",
    "extrinsic_parameters": {
        "roll": 0.11618719284657622,
        "pitch": 16.0300957665656,
        "yaw": 0.39630825451294216,
        "px": 1.6981482368157552,
        "py": -0.16870946105733092,
        "pz": 1.411771066176465
    },
    "error_stats": {
        "distance_error": {
            "average": 0.016561422963971915,
            "front_plane": 0.005801826261770239,
            "rear_plane": null,
            "right_plane": 0.007627213567991918,
            "left_plane": 0.03803306081172632,
            "ground_plane": 0.014783591214399178
        },
        "angle_error": {
            "average": 6.645093770858262,
            "front_plane": 0.3282866337907041,
            "rear_plane": null,
            "right_plane": 0.34793152531147714,
            "left_plane": 9.873651140968278,
            "ground_plane": 16.03050578336259
        }
    }
}

Get Extrinsic Parameters

This GET api call returns dataset_id, extrinsic_parameters, and error_stats.

https://tools.calibrate.deepen.ai/api/v2/external/datasets/{datasetId}/extrinsic_parameters

Request

Path parameters

Response

{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "calibration_algorithm_version": "target_based:v1.01",
    "extrinsic_parameters": {
        "roll": 0.11618719284657622,
        "pitch": 16.0300957665656,
        "yaw": 0.39630825451294216,
        "px": 1.6981482368157552,
        "py": -0.16870946105733092,
        "pz": 1.411771066176465
    },
    "error_stats": {
        "distance_error": {
            "average": 0.016561422963971915,
            "front_plane": 0.005801826261770239,
            "rear_plane": null,
            "right_plane": 0.007627213567991918,
            "left_plane": 0.03803306081172632,
            "ground_plane": 0.014783591214399178
        },
        "angle_error": {
            "average": 6.645093770858262,
            "front_plane": 0.3282866337907041,
            "rear_plane": null,
            "right_plane": 0.34793152531147714,
            "left_plane": 9.873651140968278,
            "ground_plane": 16.03050578336259
        }
    }
}

Note

The setup should prevent false detections. For example, other plane surfaces of similar shape may be identified as a board, which might give false solutions. You can always check the boards identified on the web application.