Vehicle Lidar Camera 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 images and lidar files for the given configuration. 
2.The calibration process is completed without errors if the response to the Upload and calibrate API call will contain datasetId and Status as Done. 
3.The client can call the Get Extrinsic Parameters API using the datasetId obtained from the Upload response and calibrate API. This API responds with the various extrinsic parameters, error stats, and the query's status.
Folder Structure
We require image and lidar frame pairs from the camera and lidar 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.)
3.​
Example of a Structure in zip file 
4.​
Pcd files inside the lidar file
The names of the folders and the PCDs shown here are for demonstration purposes. Users should avoid using space in the folder and the PCD names.
1.The name of the JSON file should be config.json (case sensitive)
config.json for multitarget
1
{
2
    "calibration_name": "Lidar vehicle testing ",
3
    "calibration_type": "lidar_vehicle_calibration",
4
    "vehicle_configuration":
5
    {
6
        "vehicle_shape": "rectangle",
7
        "wheelbase": 1.2,
8
        "track": 1.2,
9
        "front_wheel_overhang": 0,
10
        "rear_wheel_overhang": 0
11
    },
12
    "is_targetless_3d_lidar": false,
13
    "is_2d_lidar": false,
14
    "auto_detect_lidar_board": true,
15
    "multi_target": true,
16
    "targets":
17
    {
18
        "left":
19
        {
20
            "length": 1.2,
21
            "width": 1.8
22
        },
23
        "right":
24
        {
25
            "length": 1.2,
26
            "width": 1.8
27
        },
28
        "front":
29
        {
30
            "length": 1.2,
31
            "width": 1.8
32
        }
33
    },
34
    "use_bounding_box_on_board_detection_failure": false,
35
    "bounding_box":
36
    {
37
        "0":
38
        {
39
            "xmin": 1,
40
            "xmax": 1,
41
            "ymin": 1,
42
            "ymax": 1,
43
            "zmin": 1,
44
            "zmax": 1
45
        },
46
         "1":
47
        {
48
            "xmin": 1,
49
            "xmax": 1,
50
            "ymin": 1,
51
            "ymax": 1,
52
            "zmin": 1,
53
            "zmax": 1
54
        },
55
         "2":
56
        {
57
            "xmin": 1,
58
            "xmax": 1,
59
            "ymin": 1,
60
            "ymax": 1,
61
            "zmin": 1,
62
            "zmax": 1
63
        },
64
         "3":
65
        {
66
            "xmin": 1,
67
            "xmax": 1,
68
            "ymin": 1,
69
            "ymax": 1,
70
            "zmin": 1,
71
            "zmax": 1
72
        }
73
    },
74
    "all_lidar_data":
75
    [
76
        {
77
            "lidar_name": "Main Lidar",
78
            "laser_channels": 16,
79
            "lidar_type": "directional",
80
            "lidar_fov_direction": "front",
81
            "board_configuration_data":
82
            {
83
                "front_board_distance": 1.8,
84
                "left_board_distance": 0.6,
85
                "right_board_distance": 0.6
86
            }
87
        }
88
    ],
89
    "data":
90
    {
91
        "files":
92
        {
93
            "file": "lidar/lidardata.pcd"
94
        }
95
    }
96
}
config.json
1KB
Code
config.json for a Single target
{
    "calibration_name": "Lidar vehicle testing ",
    "calibration_type": "lidar_vehicle_calibration",
    "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,
    "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":
    {
        "0":
        {
            "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"
        }
    }
}
config.json
2KB
Code
Key
Value type
Description
calibration_name
string
Name of the calibration
lidar_type
string
directional or 360 if there are 4 boards and 3 boards respectively
vehicle_shape
string
rectangle or trapezoid  based on the shape  of the vehicle
calibration_type
string
Non-editable field.*Value should be lidar_vehicle_calibration
multi_target
boolean
true: if multiple targets are used
false: if single target is used
lidar_name
string
It is the name given by the client to the lidar. The client can modify it as willed.
targets
Object
It is a dictionary of dictionary with each dictionary having target properties. Accepted keys are
1. left
2. right
3. front
4. rear
length
double
length of the board of the target in meters
width
double
width of the board of the target in meters
tilted
Boolean
true: if the board is tilted
false: if the board is not tilted
data
Object
It stores the data related to files of the lidar
files
Object
It is an Object, where each key is a string which is "file" in case of multi-target and "left", "right", "front" or "rear" containing the path to the file.
wheelbase
double
The length from the mid of the rear wheel to the mid of the front wheel on the same side
track
double
The length from the right mid of the wheel in front of vehicle to left mid of the wheel in front of the vehicle or 
The length from the right mid of the wheel in rear of vehicle to left mid of the wheel in rear of the vehicle
vehicle_configuration
Object
Object which has all the measurements 
1. vehicle_shape
2. wheelbase
3. track 
4. front_wheel_overhang 
5. rear_wheel_overhang
breadth
double
breadth of the board of the target in meters
front_wheel_overhang
double
Overhang from the middle of the front wheels to the front end part of the vehicle in meters
rear_wheel_overhang
double
Overhang from the middle of the rear wheels to the rear end part of the vehicle in meters
is_targetless_3d_lidar
boolean
true if the calibration is targetless 
false for target-based calibration
is_2d_lidar
boolean
true if the calibration is 2d- lidar
false if the calibration is 3d-lidar
auto_detect_lidar_board
boolean
true for auto detecting the board in the point cloud
false otherwise

In most cases when using api it is true other than if bounding box is provided
use_bounding_box_on_board_detection_failure
boolean
true if bounding box should be used when detection fails
bounding_box
Object of Objects
This is an object of objects with key corresponding to the target whose details are provided.  Need to be provided if we want to use bounding box forboard detection

The keys which  gives the bounding box for a target
1. xmin
2. xmax
3. ymin
4. ymax
5. zmin
6. zmax
all_lidar_data
Object
Object with all the lidar data and board configration
laser_channels
Integer
Number of channels the lidar has .
lidar_fov_direction
string
If the lidar is directional then this defines which direction with respect to the vehicle is the lidar present. Supports 
1.front
2.rear
3.left
4.right
front_board_distance
​


double
Distance from front direction of the car to the board
left_board_distance
double
Distance from left direction of the car to the board
right_board_distance
double
Distance from right direction of the car to the board
rear_board_distance
double
Distance from rear direction of the car to the board
target_distance
double
Approximate distance between the lidar and the centroid of the board to differentiate the boards in case more than one are of similar size. needed only of the sizes are same in multiple boards


​
​
​
​
​
​
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​
API Reference
Upload file and calibrate
This API sends a zip file to the server and runs the calibration algorithm. Returns datasetId, extrinsic parameters, and status to the user as the response.
URL
POST https://tools.calibrate.deepen.ai/api/v2/external/clients/{clientId}/calibration_dataset
Request
Path parameters
Parameter name
Parameter type
Description
clientId
string
ClientId obtained from Deepen AI
Body
Key
Value
Description
file
.zip file
Zip file containing config and pcd in a suitable format
Response
JSON file containing dataset_id and status of the calibration.

Response object:
​
{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "extrinsic_parameters": {
        "roll": 0.42703553023797985,
        "pitch": -2.3421739003626802,
        "yaw": -10.228255951558245,
        "position_x": 0.5179160249705579,
        "position_y": -0.06236177033674235,
        "position_z": 0.3999455657179812
    },
    "error_stats": {
        "plane_distance_error": 0.006405542010371563
    }
}
​
Key
Status
dataset_id
A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
status
Current status of the dataset.
1.ready: Files are uploaded, and the dataset is ready for Calibration.
2.in_progress: The calibration process has started
3.done: Calibration is done. Users can query for extrinsics.
Get Extrinsic Parameters
Returns the extrinsic parameters, error statistics, and the query's status.
URL
GET https://tools.calibrate.deepen.ai/api/v2/external/datasets/{datasetId}/extrinsic_parameters
Request
Path parameters
Parameter name
Parameter type
Description
datasetId
string
datasetId obtained from the response of Upload file and calibrate API.
Response
Returns a JSON dictionary containing datasetId, extrinsic parameters, error statistics, and query status.
Response Object:
​
{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "extrinsic_parameters": {
        "roll": 0.42703553023797985,
        "pitch": -2.3421739003626802,
        "yaw": -10.228255951558245,
        "position_x": 0.5179160249705579,
        "position_y": -0.06236177033674235,
        "position_z": 0.3999455657179812
    },
    "error_stats": {
        "plane_distance_error": 0.006405542010371563
    }
}
​
Key
Description
dataset_id
A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
extrinsic_parameters
roll, pitch, and yaw are given in degrees
and px, py, and pz are given in meters.
Plane distance error
mean of the distance between the plane LiDAR points to the respective planes
Note:  The setup should be so that there are no false detections, i.e., other plane surfaces of similar shape may be identified as a board which might give false solutions. You can always check the identified boards from the web application

Parameter name	Parameter type	Description
clientId	string	ClientId obtained from Deepen AI

Key	Value	Description
file	.zip file	Zip file containing config and pcd in a suitable format

Parameter name	Parameter type	Description
datasetId	string	datasetId obtained from the response of Upload file and calibrate API.

Key	Description
dataset_id	A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
extrinsic_parameters	roll, pitch, and yaw are given in degrees and px, py, and pz are given in meters.
Plane distance error	mean of the distance between the plane LiDAR points to the respective planes

LiDAR-LiDAR Calibration API

Access token for APIs

Last modified 1mo ago

Key	Value type	Description
calibration_name	string	Name of the calibration
lidar_type	string	directional or 360 if there are 4 boards and 3 boards respectively
vehicle_shape	string	rectangle or trapezoid based on the shape of the vehicle
calibration_type	string	Non-editable field.*Value should be lidar_vehicle_calibration
multi_target	boolean	true: if multiple targets are used false: if single target is used
lidar_name	string	It is the name given by the client to the lidar. The client can modify it as willed.
targets	Object	It is a dictionary of dictionary with each dictionary having target properties. Accepted keys are 1. left 2. right 3. front 4. rear
length	double	length of the board of the target in meters
width	double	width of the board of the target in meters
tilted	Boolean	true: if the board is tilted false: if the board is not tilted
data	Object	It stores the data related to files of the lidar
files	Object	It is an Object, where each key is a string which is "file" in case of multi-target and "left", "right", "front" or "rear" containing the path to the file.
wheelbase	double	The length from the mid of the rear wheel to the mid of the front wheel on the same side
track	double	The length from the right mid of the wheel in front of vehicle to left mid of the wheel in front of the vehicle or The length from the right mid of the wheel in rear of vehicle to left mid of the wheel in rear of the vehicle
vehicle_configuration	Object	Object which has all the measurements 1. vehicle_shape 2. wheelbase 3. track 4. front_wheel_overhang 5. rear_wheel_overhang
breadth	double	breadth of the board of the target in meters
front_wheel_overhang	double	Overhang from the middle of the front wheels to the front end part of the vehicle in meters
rear_wheel_overhang	double	Overhang from the middle of the rear wheels to the rear end part of the vehicle in meters
is_targetless_3d_lidar	boolean	true if the calibration is targetless false for target-based calibration
is_2d_lidar	boolean	true if the calibration is 2d- lidar false if the calibration is 3d-lidar
auto_detect_lidar_board	boolean	true for auto detecting the board in the point cloud false otherwise In most cases when using api it is true other than if bounding box is provided
use_bounding_box_on_board_detection_failure	boolean	true if bounding box should be used when detection fails
bounding_box	Object of Objects	This is an object of objects with key corresponding to the target whose details are provided. Need to be provided if we want to use bounding box forboard detection The keys which gives the bounding box for a target 1. xmin 2. xmax 3. ymin 4. ymax 5. zmin 6. zmax
all_lidar_data	Object	Object with all the lidar data and board configration
laser_channels	Integer	Number of channels the lidar has .
lidar_fov_direction	string	If the lidar is directional then this defines which direction with respect to the vehicle is the lidar present. Supports 1. front 2. rear 3. left 4. right
front_board_distance	double	Distance from front direction of the car to the board
left_board_distance	double	Distance from left direction of the car to the board
right_board_distance	double	Distance from right direction of the car to the board
rear_board_distance	double	Distance from rear direction of the car to the board
target_distance	double	Approximate distance between the lidar and the centroid of the board to differentiate the boards in case more than one are of similar size. needed only of the sizes are same in multiple boards

Key	Status
dataset_id	A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
status	Current status of the dataset. 1. ready: Files are uploaded, and the dataset is ready for Calibration. 2. in_progress: The calibration process has started 3. done: Calibration is done. Users can query for extrinsics.