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.
How to get Access Tokens can be found on the following link: Access token for APIs​
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
Translation Error indicates the distance between the center of the boards
Rotation Error indicates the angle between the target planes
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)
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
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.
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.

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

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

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	Translation Error indicates the distance between the center of the boards Rotation Error indicates the angle between the target planes 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)

Parameter name	Parameter type	Description
dataset_Id	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.
error_stats	translation error is given in meters and rotation error is given in degrees.
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.

Lidar Camera Calibration API

Vehicle Lidar Camera Calibration API

Last modified 1mo ago

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.