Global Optimiser

Introduction

The API requires the client to upload the configuration for Global Optimisation 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 a loop_optimisation API call, which runs the loop optimisation algorithm on the calibrations for the given configuration.

2. The calibration process is completed without errors if the Loop optimisation API call response contains each calibration-id with updated extrinsics and the before and after residual error of the loop

Folder Structure

config.json contains configuration details of the loop_optimisation (dataset_ids_for_loop_optimisation, lambda_val, renamed_sensor_names and optimisation_name)

Note

The name of the JSON file should be config.json (case sensitive)

config.json

{
    "dataset_ids_for_loop_optimisation":
    [
        "NiTWuK7hYsl03dmnSXmWQ282",
        "HOb2cM5FZ1yRQUHCHupDz79y",
        "CBLukrd36IsAX75hwEDKKOWz"
    ],
    "lambda_val": 1,
    "optimisation_name": "Demo_optimisation",
    "renamed_sensor_names":
    {
        "NiTWuK7hYsl03dmnSXmWQ282":
        [
            "s1",
            "s2"
        ],
        "HOb2cM5FZ1yRQUHCHupDz79y":
        [
            "s2",
            "s3"
        ],
        "CBLukrd36IsAX75hwEDKKOWz":
        [
            "s3",
            "s1"
        ]
    }
}

Sample config.json

383B

config.json

config.json key description

Key	Type	Description
dataset_ids_for_loop_optimisation	list of strings	Calibration ids that form a loop
optimisation_name ( Optional)	string	name of the optimisation default value: "Untitled_default_name"
renamed_sensor_names (Optional)	Object	In case the sensor names don't form a loop or there is not sensor name for the calibration this can be used to to define the names of the 1st and 2nd sensor. These names are used for loop optimisation. each key in the object refers to the dataset id for which the loop optimisation will be run. each value for the key is a list of exactly two string values which refers to the new name of the sensor to be used for loop finding in order.
lamda_val ( Optional)	float	This the approximate co-relation between the the angle and distance . Default value is 1 i.e 1 degree ~ 1 meter

Quick start

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

Loop Optimisation

This POST API call sends a zip file to the server and runs the loop optimisation algorithm. As the response, it returns the updated extrinsics and the residual error before the optimisation and after the optimisation to the user.

https://tools.calibrate.deepen.ai/api/v2/external/clients/{clientId}/loop_optimisation

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

{
    "dataset_id": "tS9GBwRqa890URnCRw34tDin",
    "6QIA43UWNwdiks85lHnAc2da": {
        "original_extrinsics": {
            "roll": -91.51176360979406,
            "pitch": -0.7853331754606847,
            "yaw": -89.73580857135546,
            "px": 0.06297976077742809,
            "py": -0.2671144409542271,
            "pz": -0.06347677696290424
        },
        "optimised_extrinsics": {
            "roll": -162.78830086097742,
            "pitch": -67.70468852329144,
            "yaw": -67.75615602883266,
            "px": -0.16792771218395555,
            "py": -0.17175453956126496,
            "pz": -0.15735750873866253
        },
        "first_sensor": "s3",
        "second_sensor": "s1",
        "calibration_type": "lidar_camera_calibration"
    },
    "DIjnSTbKZ9gsci7uy5iQfHCu": {
        "original_extrinsics": {
            "roll": 1.2714894839312245,
            "pitch": -0.7715740726838012,
            "yaw": 3.757236823512545,
            "px": -0.05193859737110649,
            "py": 0.796489794765278,
            "pz": 0.023697180957906575
        },
        "optimised_extrinsics": {
            "roll": 32.69493047307559,
            "pitch": -24.39224818371977,
            "yaw": 2.684326464767165,
            "px": -0.06294408225362882,
            "py": 0.6277749217995089,
            "pz": 0.31418121569303137
        },
        "first_sensor": "s1",
        "second_sensor": "s2",
        "calibration_type": "multi_lidar_calibration"
    },
    "chTmOKGvF9LeY6PiOEObFwJr": {
        "original_extrinsics": {
            "roll": -91.37613268811,
            "pitch": 0.6464214970125648,
            "yaw": -85.92938066631706,
            "px": 0.027734081727064118,
            "py": 0.5336431958220468,
            "pz": -0.043782383437678325
        },
        "optimised_extrinsics": {
            "roll": -136.1776408027225,
            "pitch": -58.7953465856894,
            "yaw": -98.3309580011168,
            "px": 0.4195387376287298,
            "py": 0.23897812124162132,
            "pz": 0.3203764330895245
        },
        "first_sensor": "s2",
        "second_sensor": "s3",
        "calibration_type": "lidar_camera_calibration"
    },
    "residual_error": {
        "before": {
            "roll": 75.1373056595837,
            "pitch": -87.81393486062242,
            "yaw": 12.955394128297483,
            "px": 0.0080040164755718,
            "py": -0.32501818030990653,
            "pz": 0.20784293571718906
        },
        "after": {
            "roll": 1.6803259056739946e-14,
            "pitch": 6.519136608525574e-16,
            "yaw": 2.178289900990984e-16,
            "px": 4.163336342344337e-17,
            "py": 0.0,
            "pz": 1.3877787807814457e-17
        }
    }
}

Key	Description
residual_error	Key for the residual error . Values are the residual error before and after the optimisation.
roll, pitch, yaw , px, py and pz	These are the extrinsic parameters. roll, pitch, and yaw are given in degrees, and px, py, and pz are given in meters.
original_extrinsics	Extrinsics of the calibration before optimisation
optimised_extrinsics	Extrinsics after loop optimisation is done
first_sensor	first sensor name based on renaming you provided
second_sensor	second sensor name based on the renaming you provided
calibration_type	calibration_type of the calibration id

Get Extrinsic Parameters

This GET api call returns the complete dataset information for the global optimisation which is already created.

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 Global Optimisation

Response

{
    "dataset_id": "c9Cgc9JTAdSeBsdM1vyqpV2l",
    "optimisation_name": "Demo_optimisation",
    "lambda_value": 1,
    "DIjnSTbKZ9gsci7uy5iQfHCu": {
        "original_extrinsics": {
            "roll": 1.2714894839312245,
            "pitch": -0.7715740726838012,
            "yaw": 3.757236823512545,
            "px": -0.05193859737110649,
            "py": 0.796489794765278,
            "pz": 0.023697180957906575
        },
        "optimised_extrinsics": {
            "roll": 1.2714894839312245,
            "pitch": -0.7715740726838012,
            "yaw": 3.757236823512545,
            "px": -0.05193859737110649,
            "py": 0.796489794765278,
            "pz": 0.023697180957906575
        },
        "first_sensor": "s1",
        "second_sensor": "s2",
        "calibration_type": "multi_lidar_calibration"
    },
    "chTmOKGvF9LeY6PiOEObFwJr": {
        "original_extrinsics": {
            "roll": -91.37613268811,
            "pitch": 0.6464214970125648,
            "yaw": -85.92938066631706,
            "px": 0.027734081727064118,
            "py": 0.5336431958220468,
            "pz": -0.043782383437678325
        },
        "optimised_extrinsics": {
            "roll": -91.37613268811,
            "pitch": 0.6464214970125648,
            "yaw": -85.92938066631706,
            "px": 0.027734081727064118,
            "py": 0.5336431958220468,
            "pz": -0.043782383437678325
        },
        "first_sensor": "s2",
        "second_sensor": "s3",
        "calibration_type": "lidar_camera_calibration"
    },
    "6QIA43UWNwdiks85lHnAc2da": {
        "original_extrinsics": {
            "roll": -91.51176360979406,
            "pitch": -0.7853331754606847,
            "yaw": -89.73580857135546,
            "px": 0.06297976077742809,
            "py": -0.2671144409542271,
            "pz": -0.06347677696290424
        },
        "optimised_extrinsics": {
            "roll": -91.51176360979406,
            "pitch": -0.7853331754606847,
            "yaw": -89.73580857135546,
            "px": 0.06297976077742809,
            "py": -0.2671144409542271,
            "pz": -0.06347677696290424
        },
        "first_sensor": "s3",
        "second_sensor": "s1",
        "calibration_type": "lidar_camera_calibration"
    },
    "residual_error": {
        "before": {
            "roll": -89.5656191395611,
            "pitch": 1.2150671022243427,
            "yaw": -87.06145941287474,
            "px": -0.20563179812615864,
            "py": 0.00477186102247,
            "pz": -0.330607546160306
        },
        "after": {
            "roll": 5.157508393488001e-15,
            "pitch": -3.234665344111012e-15,
            "yaw": 2.5737650847597067e-16,
            "px": 2.7755575615628914e-17,
            "py": 2.7755575615628914e-17,
            "pz": -2.7755575615628914e-17
        }
    }
}

Key	Description
dataset_id	A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters.
optimisation_name	The name of the optimisation for the dataset_id
lambda_value	This the approximate co-relation between the the angle and distance . Default value is 1 i.e 1 degree ~ 1 meter
original_extrinsics	Extrinsics of the calibration before optimisation
optimised_extrinsics	Extrinsics after loop optimisation is done
first_sensor	first sensor name based on renaming you provided
second_sensor	second sensor name based on the renaming you provided
calibration_type	calibration_type of the calibration id
roll, pitch, yaw , px, py and pz	These are the extrinsic parameters. roll, pitch, and yaw are given in degrees, and px, py, and pz are given in meters.