LiDAR-LiDAR Calibration API
Introduction:
The API requires the client to upload the point clouds(only PCD format is supported) from the lidars, which needs to be calibrated along with a configuration JSON file in a zip file(.zip extension) in the format shown below. The contents of the zip file are called a dataset.
- 1.The client makes an Upload and calibrate API call, which uploads the files and runs the calibration algorithm on the lidar files uploaded with the given target 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:
Lidar frames from both lidars are needed to run the calibration.
- 1.Place the Lidar frame from the first lidar in the lidar_1 folder and place the Lidar frame from the second lidar in the lidar_2 folder.
- 2.config.json contains configuration details of the calibration
contents of zip file
contents of lidar_1 folder

contents of lidar_2 folder
- 1.
The names of the folders and the point clouds shown here are just for demonstration purposes only.
Users should avoid using space in the folder and the point cloud names.
- 2.
The name of the JSON file should be config.json (case sensitive)
config.json for multi-lidar calibration
{
"calibration_name": "multiple lidars dataset",
"calibration_type": "multi_lidar_calibration",
"multi_target": true,
"lidar_1":
{
"name": "first lidar",
"laser_channels": 16,
"height": 0.76
},
"lidar_2":
{
"name": "second lidar",
"laser_channels": 16,
"height": 0.76
},
"targets":
{
"0":
{
"length": 0.6,
"width": 1.0,
"tilted": false
},
"1":
{
"length": 1.223,
"width": 1.223,
"tilted": false
},
"2":
{
"length": 1.223,
"width": 1.223,
"tilted": false
}
},
"perform_auto_detection": true,
"initial_estimates":
{
"roll": 0,
"pitch": 0,
"yaw": 0,
"px": 0,
"py": 0,
"pz": 0
},
"data":
{
"lidar_1": "lidar_1/1.pcd",
"lidar_2": "lidar_2/2.pcd"
}
}
config.json
1012B
Code
Key | Value type | Description |
calibration_name | string | Name of calibration |
calibration_type | string | Non-editable field. Value should be multi_lidar_calibration |
multi_target | boolean | true: if multiple targets are used false: if single target is used |
lidar_1 | Object | name: It is the name given by the client to lidar_1(first lidar). The client can modify it as willed. type: string
laser_channels: It is the number of laser channels present in lidar_1 (This value is necessary to auto detect the board in lidar frame).
Supported values: 16, 32, 64, 128 and 256
type: int
height: It is the approximate height of the lidar_1 from ground.
type: double |
lidar_2 | Object | name: It is the name given by the client to lidar_2(second lidar). The client can modify it as willed. type: string
laser_channels: It is the number of laser channels present in lidar_2 (This value is necessary to auto detect the board in lidar frame).
Supported values: 16, 32, 64, 128 and 256
type: int
height: It is the approximate height of the lidar_2 from ground.
type: double |
targets | Object | It is a dictionary of dictionary with each dictionary having target properties. |
length | double | length of the target used for calibration |
width | double | width of the target used for calibration |
tilted | boolean | true: if the board is titled to the right up to 45 degrees false: if the board is not tilted |
perform_auto_detection | boolean | true: if auto board detection is required for the boards in point cloud. laser_channels property for both lidars should be provided for this property to work.
false: if auto board detection is not required |
initial_estimates | Object with all values as double | This is an optional field. The initial estimates which will be optimised to get extrinsic parameters during calibration process.
1. roll
2. pitch
3. yaw
4. px
5. py
6. pz
Note:
1. roll, pitch and yaw should be in degrees
2. px, py and pz should be in meters.
3. Delete this key if initial_estimates are not available or not to be used during calibration |
data | Object | It stores the data related to the lidar files which needs to be uploaded.
lidar_1: It is the relative path of pcd file corresponding to first lidar.
lidar_2: It is the relative path of pcd file corresponding to second lidar. |
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.
API Reference:
This API sends a zip file to the server and runs the calibration algorithm. Returns datasetId, extrinsic parameters, and information about the dataset 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 pcds in a suitable format |
Response
JSON file containing dataset_id, extrinsic parameters, and information on the calibration.
Response object:
{
"dataset_id": "XXXXXXXXXXXXXXXXXXXXXXXX",
"extrinsic_parameters": {
"roll": 0.4239873552372359,
"pitch": -0.23771056916989275,
"yaw": 0.03574130775730624,
"px": -0.20099097249221035,
"py": 0.013142481183883614,
"pz": -0.019420891404400203
},
"error_stats": {
"TRANSLATION_ERROR": 0.0007433547143350861,
"ROTATION_ERROR": 0.2269911048682634
},
"INFO": "Auto detection worked well on this dataset."
}
Key | Status |
---|---|
dataset_id | A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters. |
extrinsic_parameters | The extrinsic parameters are from the first to the second lidars for the given calibration setup. |
error_stats |
Note: If initial estimates are provided, then no error stats will be provided in the response. |
INFO | This gives general information about the dataset (like auto detection worked on this dataset or not) |
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 |
---|---|---|
dataset_Id | 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": "XXXXXXXXXXXXXXXXXXXXXXXX",
"extrinsic_parameters": {
"roll": 0.4239873552372359,
"pitch": -0.23771056916989275,
"yaw": 0.03574130775730624,
"px": -0.20099097249221035,
"py": 0.013142481183883614,
"pz": -0.019420891404400203
},
"error_stats": {
"TRANSLATION_ERROR": 0.0007433547143350861,
"ROTATION_ERROR": 0.2269911048682634
},
"status": "Done"
}
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. |
error_stats | translation error is given in meters and rotation error is given in degrees. |
status | Current status of the dataset.
|
Last modified 1mo ago