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, marker_size=3)

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

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

    # Capture images from video stream
    while video_stream.is_alive():

        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(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
    ]
}
```