Vehicle Lidar Calibration API
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.
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.
All fles in the main direcory
Sub folder structure
Pcd files inside the lidar file
- 1.The names of the folders and the lidar files shown here are for demonstration purposes. Users should avoid using space in the folder and the lidar filename.
- 2.The name of the JSON file should be
config.json(case sensitive)
1
{
2
"calibration_name": "Lidar vehicle testing ",
3
"calibration_type": "lidar_vehicle_calibration",
4
"is_lidar_tilted": false,
5
"lidar_ground_height": 1.24,
6
"vehicle_configuration":
7
{
8
"vehicle_shape": "rectangle",
9
"wheelbase": 1.2,
10
"track": 1.2,
11
"front_wheel_overhang": 0,
12
"rear_wheel_overhang": 0
13
},
14
"is_targetless_3d_lidar": false,
15
"is_2d_lidar": false,
16
"auto_detect_lidar_board": true,
17
"multi_target": true,
18
"targets":
19
{
20
"left":
21
{
22
"length": 1.2,
23
"width": 1.8
24
},
25
"right":
26
{
27
"length": 1.2,
28
"width": 1.8
29
},
30
"front":
31
{
32
"length": 1.2,
33
"width": 1.8
34
}
35
},
36
"use_bounding_box_on_board_detection_failure": false,
37
"bounding_box":
38
{
39
"left":
40
{
41
"xmin": 1,
42
"xmax": 1,
43
"ymin": 1,
44
"ymax": 1,
45
"zmin": 1,
46
"zmax": 1
47
},
48
"right":
49
{
50
"xmin": 1,
51
"xmax": 1,
52
"ymin": 1,
53
"ymax": 1,
54
"zmin": 1,
55
"zmax": 1
56
},
57
"front":
58
{
59
"xmin": 1,
60
"xmax": 1,
61
"ymin": 1,
62
"ymax": 1,
63
"zmin": 1,
64
"zmax": 1
65
}
66
},
67
"all_lidar_data":
68
[
69
{
70
"lidar_name": "Main Lidar",
71
"laser_channels": 16,
72
"lidar_type": "directional",
73
"lidar_fov_direction": "front",
74
"board_configuration_data":
75
{
76
"front_board_distance": 1.8,
77
"left_board_distance": 0.6,
78
"right_board_distance": 0.6
79
}
80
}
81
],
82
"data":
83
{
84
"files":
85
{
86
"file": "lidar/lidardata.pcd"
87
}
88
}
89
}
config.json
2KB
Code
{
"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,
"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"
}
}
}
config.json
2KB
Code
Key | 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
|
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 |
is_lidar_tilted | Boolean | If the lidar is tilted autodetection happends else if the lidar ground heigh is given then ground is detected at that much distance from ground |
lidar_ground_height | number | distance from ground to the lidar when lidar is parallel to ground |
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
This API sends a zip file to the server and runs the calibration algorithm. Returns dataset_id, extrinsic_parameters, and error_stats to the user as the response.
https://tools.calibrate.deepen.ai/api/v2/external/clients/{clientId}/calibration_datasetRequest
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
{
"dataset_id": "XXXXXXXXXXXXXXXXX",
"extrinsic_parameters": {
"roll": 0.42703553023797985,
"pitch": -2.3421739003626802,
"yaw": -10.228255951558245,
"px": 0.5179160249705579,
"py": -0.06236177033674235,
"pz": 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. |
error_stats | plane_distance_error is the mean of the distance between the plane LiDAR points to the respective planes. |
JSON response containing dataset_id, extrinsic_parameters, and error_stats.
https://tools.calibrate.deepen.ai/api/v2/external/datasets/{datasetId}/extrinsic_parametersRequest path parameters
Parameter name | Parameter type | Description |
|---|---|---|
datasetId | string | datasetId obtained from the response of Upload file and calibrate API. |
Response
{
"dataset_id": "XXXXXXXXXXXXXXXXX",
"extrinsic_parameters": {
"roll": 0.42703553023797985,
"pitch": -2.3421739003626802,
"yaw": -10.228255951558245,
"px": 0.5179160249705579,
"py": -0.06236177033674235,
"pz": 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. |
error_stats | plane_distance_error is the mean of the distance between the plane LiDAR points to the respective planes. |
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.
Last modified 47m ago