Calibrate optic parameters
==========================

A camera device have to be calibrated to compensate its optical distorsion.

![Optic parameters calibration](../../../img/optic_calibration.png)

## Print calibration board

The first step to calibrate a camera is to create an [ArUcoBoard](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) like in the code below:

``` python
from argaze.ArUcoMarkers import ArUcoMarkersDictionary, ArUcoBoard

# Create ArUco dictionary
aruco_dictionary = ArUcoMarkersDictionary.ArUcoMarkersDictionary('DICT_APRILTAG_16h5')

# Create an ArUco board of 7 columns and 5 rows with 5 cm squares with 3cm ArUco markers inside
aruco_board = ArUcoBoard.ArUcoBoard(7, 5, 5, 3, aruco_dictionary)

# Export ArUco board with 300 dpi resolution
aruco_board.save('./calibration_board.png', 300)
```

!!! note
      There is **A3_DICT_APRILTAG_16h5_3cm_35cmx25cm.pdf** file located in *./src/argaze/ArUcoMarkers/utils/* folder ready to be printed on A3 paper sheet.

Let's print the calibration board before to go further.

## Capture board pictures 

Then, the calibration process needs to make many different captures of an [ArUcoBoard](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) through the camera and then, pass them to an [ArUcoDetector](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector.ArUcoDetector) instance to detect board corners and store them as calibration data into an [ArUcoOpticCalibrator](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator) for final calibration process.

![Calibration step](../../../img/optic_calibration_step.png)

The sample of code below illustrates how to:

* load all required ArGaze objects,
* detect board corners into a Full HD camera video stream, 
* store detected corners as calibration data then, 
* once enough captures are made, process them to find optic parameters and, 
* finally, save optic parameters into a JSON file.

``` python
from argaze.ArUcoMarkers import ArUcoMarkersDictionary, ArUcoOpticCalibrator, ArUcoBoard, ArUcoDetector

# Create ArUco dictionary
aruco_dictionary = ArUcoMarkersDictionary.ArUcoMarkersDictionary('DICT_APRILTAG_16h5')

# Create ArUco optic calibrator
aruco_optic_calibrator = ArUcoOpticCalibrator.ArUcoOpticCalibrator()

# Create ArUco board of 7 columns and 5 rows with 5 cm squares with 3cm aruco markers inside
# Note: This board is the one expected during further board tracking
expected_aruco_board = ArUcoBoard.ArUcoBoard(7, 5, 5, 3, aruco_dictionary)

# Create ArUco detector
aruco_detector = ArUcoDetector.ArUcoDetector(dictionary=aruco_dictionary)

# Assuming that live Full HD (1920x1080) video stream is enabled
...

# Assuming there is a way to escape the while loop
...

    while video_stream.is_alive():

        # Capture image from video stream
        image = video_stream.read()

        # Detect all board corners in image
        aruco_detector.detect_board(image, expected_aruco_board, expected_aruco_board.markers_number)

        # If all board corners are detected
        if aruco_detector.board_corners_number() == expected_aruco_board.corners_number:

            # Draw board corners to show that board tracking succeeded
            aruco_detector.draw_board(image)

            # Append tracked board data for further calibration processing 
            aruco_optic_calibrator.store_calibration_data(aruco_detector.board_corners(), aruco_detector.board_corners_identifier())

# Start optic calibration processing for Full HD image resolution
print('Calibrating optic...')
optic_parameters = aruco_optic_calibrator.calibrate(expected_aruco_board, dimensions=(1920, 1080))

if optic_parameters:

    # Export optic parameters
    optic_parameters.to_json('./optic_parameters.json')

    print('Calibration succeeded: optic_parameters.json file exported.')

else:

    print('Calibration failed.')
```

Below, an optic_parameters JSON file example:

```json
{
    "rms": 0.6688921504088245,
    "dimensions": [
        1920,
        1080
    ],
    "K": [
        [
            1135.6524381415752,
            0.0,
            956.0685325355497
        ],
        [
            0.0,
            1135.9272506869524,
            560.059099810324
        ],
        [
            0.0,
            0.0,
            1.0
        ]
    ],
    "D": [
        0.01655492265003404,
        0.1985524264972037,
        0.002129965902489484,
        -0.0019528582922179365,
        -0.5792910353639452
    ]
}
```

## Load and display optic parameters

[ArUcoCamera.detector.optic_parameters](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator.OpticParameters) can be enabled thanks to a dedicated JSON entry.

Here is an extract from the JSON [ArUcoCamera](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration file where optic parameters are loaded and displayed:

```json
{
    "name": "My FullHD Camera",
    "size": [1920, 1080],
    "aruco_detector": {
        "dictionary": "DICT_APRILTAG_16h5",
        "optic_parameters": {
            "rms": 0.6688921504088245,
            "dimensions": [
                1920,
                1080
            ],
            "K": [
                [
                    1135.6524381415752,
                    0.0,
                    956.0685325355497
                ],
                [
                    0.0,
                    1135.9272506869524,
                    560.059099810324
                ],
                [
                    0.0,
                    0.0,
                    1.0
                ]
            ],
            "D": [
                0.01655492265003404,
                0.1985524264972037,
                0.002129965902489484,
                -0.0019528582922179365,
                -0.5792910353639452
            ]
        }
    },
    ...
    "image_parameters": {
        ...
        "draw_optic_parameters_grid": {
            "width": 192,
            "height": 108,
            "z": 100,
            "point_size": 1,
            "point_color": [0, 0, 255]
        }
    }
```