The API requires the client to upload the PCDs and configuration for LiDAR-LiDAR setup in a zip file (.zip extension) in the format defined below. The contents of the zip file are called a dataset.
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
The calibration process is completed without errors if the Upload and calibrate API call response contains dataset_id, calibration_algorithm_version, extrinsic_parameters, and error_stats.
The client can fetch the extrinsic parameters using the dataset_id obtained from the Upload and calibrate API. This API responds with dataset_id, calibration_algorithm_version, extrinsic_parameters, and error_stats.
Lidar frames from both lidars are needed to run the calibration.
Place the Lidar frame from the first lidar in the lidar_1 folder and the Lidar frame from the second lidar in the lidar_2 folder. Provide the mappings of corresponding pcds in the config.
config.json contains configuration details of the calibration
Note: Folder structure is optional. Users can place all files in the main directory and zip it.
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 filenames.
The name of the JSON file should be config.json (case sensitive)
calibration_name
string
Name of calibration
calibration_type
string
Non-editable field. Value should be multi_lidar_calibration
calibration_group_id
string
This is an optional key. Provide valid calibration_group_id to add the dataset to calibration group.
multi_target
boolean
true: if multiple targets are used
false: if single target is used
is_target_based
boolean
true: if the calibration uses target based approach false: if the calibration uses targetless based approach
algorithm_name
string
It is the algorithm which needs to be used to perform calibration. Supported values: 'gicp' , 'ndt' , 'custom_gicp' gicp - works best for dense point clouds ndt - works best for sparse point clouds custom_gicp - modified version of gicp, works best if there are good amount of ground points in both the lidar frames.
voxel_size
double
This key is required only when ndt algorithm is selected. voxel_size value is adjusted depending on the indoor/outdoor environment.
Note:
For outdoor environment, its preferable to have a smaller voxel_size, and for indoors, a larger voxel_size is prefered.
If voxel_size is not given, default value of 0.5 is considered
max_correspondance
double
This key is required only when custom_gicp algorithm is selected.
Note:
Accepted range is from 0 to 1
If max_correspondance is not given, default value of 0.2 is considered.
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
ground_plane: list of lists where each list value is the equation of the ground plane in frame of reference of this lidar. It is expected to be a list of size 4 with the following convention:
ground plane with [a, b, c, d] signifies the ground plane has the equation
a*x + b*y + c*z + d = 0 Note: This ground plane equation is required only if the selected algorithm is custom_gicp.
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
ground_plane: list of lists where each list value is the equation of the ground plane in frame of reference of this lidar. It is expected to be a list of size 4 with the following convention: ground plane with [a, b, c, d] signifies the ground plane has the equation
a*x + b*y + c*z + d = 0 Note: This ground plane equation is required only if the selected algorithm is custom_gicp.
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 (targetbased ) / folder path(targetless) corresponding to first lidar lidar_2: It is the relative path of pcd file (targetbased ) / folder path(targetless) corresponding to second lidar.
boolean
Optional Argument incase you have old zip file with single pair of lidars default: True
mappings
list of lists
each list value is a list with 1st value corresponding to lidar1 and 2nd value corresponding to lidar 2
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 POST api call sends a zip file to the server and runs the calibration algorithm. Returns dataset_id, calibration_algorithm_version, extrinsic_parameters, and error_stats to the user as the response.
https://tools.calibrate.deepen.ai/api/v2/external/clients/{clientId}/calibration_dataset
clientId
string
ClientId obtained from Deepen AI
file
.zip file
Zip file containing config and pcds in a suitable format
dataset_id
A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
calibration_algorithm_version
The version of the algorithm used to calculate extrinsic parameters. This value can be used to map extrinsic parameters to a specific algorithm version.
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, error_stats can't be calculated
INFO
This gives general information about the dataset (like auto-detection worked on this dataset or not)
dataset_id
A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
calibration_algorithm_version
The version of the algorithm used to calculate extrinsic parameters. This value can be used to map extrinsic parameters to a specific algorithm version.
extrinsic_parameters
The extrinsic parameters are from the first to the second lidars for the given calibration setup.
estimated_error_value
It is an error in the extrinsic parameters estimated from the fitness score of the algorithm used.
This GET api call returns dataset_id, calibration_algorithm_version, extrinsic_parameters, and error_stats.
https://tools.calibrate.deepen.ai/api/v2/external/datasets/{datasetId}/extrinsic_parameters
dataset_Id
string
datasetId obtained from the response of Upload file and calibrate API.
dataset_id
A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
calibration_algorithm_version
The version of the algorithm used to calculate extrinsic parameters. This value can be used to map extrinsic parameters to a specific algorithm version.
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.
dataset_id
A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
calibration_algorithm_version
The version of the algorithm used to calculate extrinsic parameters. This value can be used to map extrinsic parameters to a specific algorithm version.
extrinsic_parameters
roll, pitch, and yaw are given in degrees and px, py, and pz are given in meters.
estimated_error_value
It is an error in the extrinsic parameters estimated from the fitness score of the algorithm used.
