Overlapping Camera Calibration API
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 for the given 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 make a call to the Get Extrinsic Parameters API using the datasetId obtained from the response of the Upload and calibrate API. This API responds with the various extrinsic parameters, error stats, and the query's status.
We require pairs of images from Camera-1 and Camera-2 for a given calibration.
- 1.Place the images captured from Camera-1 in a folder.
- 2.Place the images captured from Camera-2 in a folder.
- 3.config.json contains configuration details of the calibration (intrinsic parameters, calibration name, etc.)

Contents of the Zip

Contents of Camera-1 folder

Contents of Camera-2 folder
- 1.The names of the folders and the images shown here are for demonstration purposes. Users are suggested to avoid using space in the folder and the image names.
- 2.The name of the JSON file should be config.json (case sensitive)
{
"calibration_name": "Stereo camera targetless test json",
"calibration_type": "stereo_camera_calibration",
"calibration_approach": "targetless",
"version": 1,
"sensors": [
{
"type": "camera",
"name": "camera-1",
"lens_model": "pinhole",
"order": 1,
"distance_between_two_cameras": 0.15,
"intrinsics": {
"fx": 3122.194743256745,
"fy": 3122.181710723859,
"cx": 1986.528401021716,
"cy": 1521.5095985734367,
"k1": 0.0769220623362174,
"k2": -0.2986932352978846,
"p1": 0.0006017554672330459,
"p2": -0.000012897857462863151,
"k3": 0.27916217745717664,
"distortion_enabled": false
}
},
{
"type": "camera",
"name": "camera-2",
"lens_model": "pinhole",
"order": 2,
"distance_between_two_cameras": 0.15,
"intrinsics": {
"fx": 3673.077123835131,
"fy": 3679.13918441065,
"cx": 2265.000932584236,
"cy": 1734.609771551174,
"k1": -0.062337924932653985,
"k2": 0.3059745937362206,
"k3": -0.3007583796119363,
"p1": 0.0022888690745840696,
"p2": -0.00039452855337905547,
"distortion_enabled": false
}
}
],
"data": {
"mappings": [
[
"camera-1/Camera-1_Image-1.jpg",
"camera-2/Camera-2_Image-1.jpg"
],
[
"camera-1/Camera-1_Image-2.jpg",
"camera-2/Camera-2_Image-2.jpg"
]
]
}
}
config.json
2KB
Code
Key | Value type | Description |
---|---|---|
calibration_name | string | Name of the calibration |
calibration_type | string | Non-editable field. *Value should be stereo_camera_calibration |
calibration_approach | string | Non-editable field. *Value should be targetless |
version | integer | Non-editable field
*Value should be kept 1. |
type | string | Non-editable field Describes the kind of sensor, *value should be kept 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
|
order | int | An integer value to differentiate Camera-1 and Camera-2 inputs.
|
distance_between_two_cameras | double | Distance between Camera-1 and Camera-2 in meters. |
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:
|
data | dict | It stores the data related to mapping of the images |
mappings | List of lists | It is a list of lists, where each sub-list is a tuple containing names of the images paired together. Note:
|
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 over it.
Returns datasetId and status 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 images in a suitable format |
Response
JSON file containing dataset_id and status of the calibration.
Response object:
{
"dataset_id": "xxxxxxxxxxxxxxxxxx",
"status": "done"
}
Key | Status |
---|---|
dataset_id | A unique value to identify the dataset. dataset_id can be used to retrieve the extrinsic parameters. |
status | Current status of the dataset.
|
- 1.Missing keys in the config.json (Example: order key is missing)
- 2.If the data is empty.
'status': "error no files found"
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 |
---|---|---|
datasetId | 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": "xxxxxxxxxxxxxxxxxx",
"extrinsic_parameters": {
"roll": 0.6125014642428289,
"pitch": 23.73096448736478,
"yaw": 0.2760998869265284,
"px": 1.063272312312118,
"py": -0.123418943241223478,
"pz": -0.912311425189295
},
"error_stats": {
"avg_epipolar_error": 0.0099796504,
"avg_epiline_point_distance": 0.12312458
},
"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 | Epiline Point Distance: Average pixel distance of each point to its corresponding projected epiline. Epipolar Error: Proportional to the distance of a point from its epiline. Does not have a physical meaning. It is the residual error from minimizing the epipolar constraints while calculating the fundamental/essential matrix |
Last modified 1mo ago