Overlapping 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 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.
Folder Structure
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

Note: 
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)
config.json
{
    "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
1.pinhole
2.fisheye
order
int
An integer value to differentiate Camera-1 and Camera-2 inputs.
1.order = 1 for Camera-1
2.order = 2 for Camera-2
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: 
1.If the lens_model is pinhole we require k1, k2, k3, p1, and p2 values (no need of k4) 
2.If the lens_model is fisheye then we require the k1, k2, k3, and k4 values. (p1 and p2 are not needed)
3.These parameters are not required if distortion_enabled is false.
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: 
1.The first element in the tuple should be the image path from the first camera (Camera-1)
2.The second element in the tuple should be the image path from the second camera (Camera-2).
3.The client can name their images as they want, but they must have the same name in the mapping list and be present in the suitable folder.
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

API Reference
Upload file and calibrate
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.ready: Files are uploaded and the dataset is ready for Calibration.
2.in_progress: The calibration process has started
3.done: Calibration is done. Users can query for extrinsics.
Errors
1.Missing keys in the config.json (Example: order key is missing)
​
2.If the data is empty. 'status': "error no files found"
Get Extrinsic Parameters
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
​

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 1. pinhole 2. fisheye
order	int	An integer value to differentiate Camera-1 and Camera-2 inputs. 1. order = 1 for Camera-1 2. order = 2 for Camera-2
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: 1. If the lens_model is pinhole we require k1, k2, k3, p1, and p2 values (no need of k4) 2. If the lens_model is fisheye then we require the k1, k2, k3, and k4 values. (p1 and p2 are not needed) 3. These parameters are not required if distortion_enabled is false.
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: 1. The first element in the tuple should be the image path from the first camera (Camera-1) 2. The second element in the tuple should be the image path from the second camera (Camera-2). 3. The client can name their images as they want, but they must have the same name in the mapping list and be present in the suitable folder.

Parameter name	Parameter type	Description
clientId	string	ClientId obtained from Deepen AI

Key	Value	Description
file	.zip file	Zip file containing config and images in a suitable format

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. ready: Files are uploaded and the dataset is ready for Calibration. 2. in_progress: The calibration process has started 3. done: Calibration is done. Users can query for extrinsics.

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

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