Target 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. If the Upload and calibrate API call response contains dataset_id, extrinsic_parameters, and error_stats, the calibration process is completed without errors.

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, extrinsic_parameters, and error_stats.

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.)

Note: Folder structure is optional. Users can place all files in the main directory and zip it.

All fles in the main direcory

Sub folder structure

Note:

1. The names of the folders and the images shown here are for demonstration purposes. Users should 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 target test json",
    "calibration_type": "stereo_camera_calibration",
    "calibration_approach": "target",
    "calibration_group_id": "xxxxxxxxxxxxxxxxxx",
    "camera_name": "testing",
    "version": 1,
    "sensors":
    [
        {
            "type": "camera",
            "camera_name": "camera-1",
            "lens_model": "pinhole",
            "order": 1,
            "intrinsics":
            {
                "fx": 637.9979043862676,
                "fy": 637.2913304517151,
                "cx": 308.57241376563456,
                "cy": 249.3219705972806,
                "k1": 0.010836839123302482,
                "k2": -0.1681481749617312,
                "k3": 0.34212352105883226,
                "p1": -0.0015508201538298647,
                "p2": 0.0007262040491250433,
                "distortion_enabled": true
            }
        },
        {
            "type": "camera",
            "camera_name": "camera-2",
            "lens_model": "pinhole",
            "order": 2,
            "intrinsics":
            {
                "fx": 551.8229800889904,
                "fy": 552.5836984848693,
                "cx": 330.7184777334105,
                "cy": 239.21866259687843,
                "k1": 0.041093020494831226,
                "k2": -0.28304021925492207,
                "k3": 0.34927796234849,
                "p1": -0.0013944256202909208,
                "p2": 0.002079203507227741,
                "distortion_enabled": true
            }
        }
    ],
    "target":
    {
        "type": "checkerboard",
        "horizontal_corners": 9,
        "vertical_corners": 7,
        "square_size": 0.023
    },
    "data":
    {
        "mappings":
        [
            [
                "Camera-1/left1.png",
                "Camera-2/right1.png"
            ],
            [
                "Camera-1/left2.png",
                "Camera-2/right2.png"
            ],
            [
                "Camera-1/left3.png",
                "Camera-2/right3.png"
            ],
            [
                "Camera-1/left4.png",
                "Camera-2/right4.png"
            ],
            [
                "Camera-1/left5.png",
                "Camera-2/right5.png"
            ],
            [
                "Camera-1/left6.png",
                "Camera-2/right6.png"
            ],
            [
                "Camera-1/left7.png",
                "Camera-2/right7.png"
            ],
            [
                "Camera-1/left8.png",
                "Camera-2/right8.png"
            ],
            [
                "Camera-1/left9.png",
                "Camera-2/right9.png"
            ],
            [
                "Camera-1/left10.png",
                "Camera-2/right10.png"
            ]
        ]
    }
}

Sample config.json

3KB

config.json

config.json key description

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 target
calibration_group_id	string	This is an optional key. Provide valid calibration_group_id to add the dataset to calibration group.
camera_name	string	It is the name given by the client to the camera. The client can modify it as willed.
version	integer	Non-editable field *Value should be kept 1.
lens_model	string	Describes the type of lens used by the camera. Accepted values pinhole fisheye
order	int	An integer value to differentiate Camera-1 and Camera-2 inputs. order = 1 for Camera-1 order = 2 for Camera-2
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.
target.type	string	Non-editable field. *Value should be checkerboard
horizontal_corners	int	Total number of horizontal inner corners in the checkerboard
vertical_corners	int	Total number of vertical inner corners in the checkerboard
square_size	double	size of the square in the checkerboard
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: The first element in the tuple should be the image path from the first camera (Camera-1) The second element in the tuple should be the image path from the second camera (Camera-2). 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

Upload file and calibrate

This POST api call sends a zip file to the server and runs the calibration algorithm. Returns dataset_id, 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 the above format

Response

{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "extrinsic_parameters": {
        "roll": 3.9392705684456364,
        "pitch": -0.2310802575353352,
        "yaw": -1.4146200834601126,
        "px": -0.14554188057541445,
        "py": 0.011603393518656024,
        "pz": -0.024766745488969955
    },
    "error_stats": {
        "mean_reprojection_error": {
            "left": 0.0719646155834198,
            "right": 0.17140584141016008
        },
        "mean_rotation_error": 0.6298996732271478,
        "mean_translation_error": 0.00100630686100607
    }
}

Key	Status
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	mean_reprojection_error left: Mean of the pixel error when the detected corners from the right image are projected onto the left image using the calibration results right: Mean of the pixel error when the detected corners from the left image are projected onto the right image using the calibration results mean_rotation_error: Mean of the angle between the planes of the 3D projections in a 3D scene of the checkerboard from the left images and right images mean_translation_error: Mean of the distance between the means of the 3D projections of the checkerboard in a 3D scene from the left images and right images

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

This GET api call returns dataset_id, extrinsic_parameters, and error_stats.

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

{
    "dataset_id": "XXXXXXXXXXXXXXXXX",
    "extrinsic_parameters": {
        "roll": 3.9392705684456306,
        "pitch": -0.23108025753533196,
        "yaw": -1.4146200834601057,
        "px": -0.14554188057541467,
        "py": 0.011603393518656718,
        "pz": -0.024766745488969732
    },
    "error_stats": {
        "mean_reprojection_error": {
            "left": 0.0719646155834198,
            "right": 0.17140584141016008
        },
        "mean_rotation_error": 0.6298996732270024,
        "mean_translation_error": 0.0010063068610060364
    }
}

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	mean_reprojection_error left: Mean of the pixel error when the detected corners from the right image are projected onto the left image using the calibration results right: Mean of the pixel error when the detected corners from the left image are projected onto the right image using the calibration results mean_rotation_error: Mean of the angle between the planes of the 3D projections in a 3D scene of the checkerboard from the left images and right images mean_translation_error: Mean of the distance between the means of the 3D projections of the checkerboard in a 3D scene from the left images and right images