Radar Camera Calibration API

Introduction

The API requires the client to upload the images and configuration for camera 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 images and 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, calibration_algorithm_version, 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, calibration_algorithm_version, extrinsic_parameters, and error_stats.

Folder Structure

We require the images from the camera for a given calibration.

1. Place the images captured from the camera 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 files in the main directory

Note

1. The names of the folders and the images shown here are for demonstration purposes. Users should avoid using space in the folder, lidar, and image filenames.

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

config.json

{
    "calibration_name": "Radar camera calibration",
    "calibration_type": "radar_camera_calibration",
    "calibration_group_id": "xxxxxxxxxxxxxxxxxx",
    "multi_target": true,
    "intrinsics":
    {
        "camera_name": "camera name",
        "fx": 2204.465766956982,
        "fy": 2200.718949580785,
        "cx": 1987.2093520754504,
        "cy": 1489.9660572902758,
        "k1": -0.23936177115777293,
        "k2": 0.08598068870627995,
        "p1": -0.00022312630506811154,
        "p2": -0.00014031224535402575,
        "k3": -0.017426786421056686,
        "lens_model": "pinhole",
        "distortion_enabled": true
    },
    "targets":
    {
        "0":
        {
            "rows": 14,
            "columns": 14,
            "type": "charucoboard",
            "square_size": 0.08708571428,
            "marker_size": 0.06966857142,
            "dictionary": "5X5",
            "padding_right": 0,
            "padding_left": 0,
            "padding_top": 0,
            "padding_bottom": 0,
            "thickness": 0.017,
            "reflector_edge_length": 0.15
        },
        "1":
        {
            "rows": 13,
            "columns": 13,
            "type": "charucoboard",
            "square_size": 0.09378461538,
            "marker_size": 0.0750276923,
            "dictionary": "6X6",
            "padding_right": 0,
            "padding_left": 0,
            "padding_top": 0,
            "padding_bottom": 0,
            "thickness": 0.017,
            "reflector_edge_length": 0.097
        }
    },
    "radar_targets":
    {
        "file_data":
        [
            {
                "file_name": "IMG_20231026_171948_00_035.jpg",
                "position":
                {
                    "0":
                    {
                        "x": -1.117985,
                        "y": 1.391907,
                        "z": -0.111471
                    },
                    "1":
                    {
                        "x": 0.077714,
                        "y": 2.48555,
                        "z": -0.018687
                    }
                }
            },
            {
                "file_name": "IMG_20231026_173234_00_036.jpg",
                "position":
                {
                    "0":
                    {
                        "x": -1.117985,
                        "y": 1.390701,
                        "z": -0.125626
                    },
                    "1":
                    {
                        "x": 0.850759,
                        "y": 1.913570,
                        "z": 0.005958
                    }
                }
            },
            {
                "file_name": "IMG_20231026_174525_00_037.jpg",
                "position":
                {
                    "0":
                    {
                        "x": -1.183428,
                        "y": 2.430081,
                        "z": 0.105416
                    },
                    "1":
                    {
                        "x": 0.514892,
                        "y": 1.679770,
                        "z": -0.000271
                    }
                }
            },
            {
                "file_name": "IMG_20231026_175017_00_038.jpg",
                "position":
                {
                    "0":
                    {
                        "x": 0.744415,
                        "y": 1.673840,
                        "z": 0.042591
                    },
                    "1":
                    {
                        "x": -1.413842,
                        "y": 2.254565,
                        "z": -0.027773
                    }
                }
            },
            {
                "file_name": "IMG_20231026_175521_00_039.jpg",
                "position":
                {
                    "0":
                    {
                        "x": 0.644887,
                        "y": 1.761710,
                        "z": -0.001819
                    },
                    "1":
                    {
                        "x": -1.413842,
                        "y": 2.253737,
                        "z": -0.067103
                    }
                }
            }
        ]
    }
}

Sample config.json

4KB

config.json

config.json key description

Key	Type	Description
calibration_name	string	Name of the calibration
calibration_type	string	Non-editable field. Value should be radar_camera_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
camera_name	string	It is the name given by the client to the camera. The client can modify it as willed.
lens_model	string	Describes the type of lens used by the camera. Accepted values pinhole fisheye
fx	double	Focal length of the cameras in the X-axis. Value in pixels.
fy	double	Focal length of the camera in the Y-axis. Value in pixels.
cx	double	Optical centre of the camera in the X-axis. Value in pixels.
cy	double	Optical centre of the camera in the Y-axis. Value in pixels.
distortion_enabled	boolean	Makes use of distortion coefficients (k1, k2, k3, k4, p1, p2) for the calibration algorithm when set true. Distortion coefficients (k1, k2, k3, k4, p1, p2) are not required if it is false.
k1, k2, k3, k4, p1, p2	double	These are the values for distortion coefficients of the camera lens.Note: If the lens_model is pinhole we require k1, k2, k3, p1, and p2 values (no need of k4) If the lens_model is fisheye then we require the k1, k2, k3, and k4 values. (p1 and p2 are not needed) These parameters are not required if distortion_enabled is false.
targets	Object	It is a dictionary of dictionary with each dictionary having target properties
type	string	Describes the type of target used. Accepted values checkerboard charucoboard
x (or) horizontal_corners	integer	number of horizontaol corners in the checkerboard (this property is needed if the type = checkerboard)
y (or) vertical_corners	integer	number of vertical corners in the checkerboar (this property is needed if the type = checkerboard)
rows	integer	number of horizontaol squares in the charucoboard (this property is needed if the type is charucoboard)
columns	integer	number of vertical squares in the charucoboard (this property is needed if the type is charcuboard)
square_size	double	Size of each square in meters
marker_size	double	The size of marker in a charucoboard in meters ( Normally it is 0.8 times of square size ) (this property is needed if the type is charucoboard)
dictionary	string	It is the string that defines the charuco dictionary of the target. We support 4X4 5X5 6X6 7X7 original charuco_apriltag_36h11 charuco_apriltag_25h9 This property is needed if the type is charucoboard
padding_right	double	padding to the right of the board
padding_left	double	padding to the left of the board
padding_top	double	padding to the top of the board
padding_bottom	double	padding to the bottom of the board
radar_targets	Object	It stores the data related to position of radar target
file_data	List of Objects	It stores the file_name and position
file_name	String	Name of the image file (a file with this name should be available in the zip file)
position	Object	Contains the x, y and z coordinates of the radar-target.

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

Upload file and calibrate

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

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 images in a suitable format

Response

{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "calibration_algorithm_version": "XXXXXXXXXXXXXXXXX",
    "extrinsic_parameters": {
        "roll": -90.47755237974575,
        "pitch": -0.38434110269976385,
        "yaw": -87.95967045393508,
        "px": 0.06958801619530329,
        "py": -0.28251980028661544,
        "pz": -0.010306058948604074
    },
    "error_stats": {
        "translation_error": {
            "IMG_20231026_171948_00_035.jpg": 0.3020655174664843,
            "IMG_20231026_173234_00_036.jpg": 0.30081030974787387,
            "IMG_20231026_174525_00_037.jpg": 0.07071623324393249,
            "IMG_20231026_175017_00_038.jpg": 0.23386259022431746,
            "IMG_20231026_175521_00_039.jpg": 0.24004605472611307
        },
        "mean_translation_error": 0.24997455895028214,
        "reprojection_error": {
            "IMG_20231026_171948_00_035.jpg": 278.64663357313,
            "IMG_20231026_173234_00_036.jpg": 306.10811229939486,
            "IMG_20231026_174525_00_037.jpg": 130.23295364437632,
            "IMG_20231026_175017_00_038.jpg": 304.5295288314502,
            "IMG_20231026_175521_00_039.jpg": 352.52075250097744
        },
        "mean_reprojection_error": 274.40759616986577
    }
}

Key	Description
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: The translational error rate gives the mean distance error between points in 3D (it is for individual files) mean_translation_error: Mean of the translation_error of all the files. reprojection_error: The reprojection error rate gives the mean distance error between points in 2D (it is for individual files) mean_reprojection_error: Mean of the reprojection_error of all the files

Get Extrinsic Parameters

This GET api call 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/datasets/{dataset_id}/extrinsic_parameters

Request

Path parameters

Parameter name	Parameter type	Description
dataset_id	string	dataset_id obtained from the response of Upload file and calibrate API.

Response

{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "calibration_algorithm_version": "XXXXXXXXXXXXXXXXX",
    "extrinsic_parameters": {
        "roll": -90.47755237974575,
        "pitch": -0.38434110269976385,
        "yaw": -87.95967045393508,
        "px": 0.06958801619530329,
        "py": -0.28251980028661544,
        "pz": -0.010306058948604074
    },
    "error_stats": {
        "translation_error": {
            "IMG_20231026_171948_00_035.jpg": 0.3020655174664843,
            "IMG_20231026_173234_00_036.jpg": 0.30081030974787387,
            "IMG_20231026_174525_00_037.jpg": 0.07071623324393249,
            "IMG_20231026_175017_00_038.jpg": 0.23386259022431746,
            "IMG_20231026_175521_00_039.jpg": 0.24004605472611307
        },
        "mean_translation_error": 0.24997455895028214,
        "reprojection_error": {
            "IMG_20231026_171948_00_035.jpg": 278.64663357313,
            "IMG_20231026_173234_00_036.jpg": 306.10811229939486,
            "IMG_20231026_174525_00_037.jpg": 130.23295364437632,
            "IMG_20231026_175017_00_038.jpg": 304.5295288314502,
            "IMG_20231026_175521_00_039.jpg": 352.52075250097744
        },
        "mean_reprojection_error": 274.40759616986577
    }
}

Key	Description
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: The translational error rate gives the mean distance error between points in 3D (it is for individual files). mean_translation_error: Mean of the translation_error of all the files. reprojection_error: The reprojection error rate gives the mean distance error between points in 2D (it is for individual files) mean_reprojection_error: Mean of the reprojection_error of all the files